Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

The Compressor Capability Structure

Image compressor components use the compressor capability structure to report their capabilities to the Image Compression Manager. Before compressing or decompressing an image, the Image Compression Manager requests this capability information from the component that will be handling the operation by calling the CDPreCompress or CDPreDecompress function provided by that component. The compressor component examines the compression or decompression parameters and indicates any restrictions on its ability to satisfy the request in a formatted compressor capability structure. The Image Compression Manager then manages the operation according to the capabilities of the component.

The CodecCapabilities data type defines the compressor capability structure.

typedef struct {
    long                flags;                  /* control information */
    short               wantedPixelSize;        /* pixel depth for component
                                                    to use with image */
    short               extendWidth;            /* extension width of image
                                                    in pixels */
    short               extendHeight;           /* extension height of image
                                                    in pixels */
    short               bandMin;                /* supported minimum
                                                    image band height */
    short               bandInc;                /* common factor of
                                                    supported band heights */
    short               pad;                    /* reserved */
    unsigned long       time;                   /* milliseconds operation
                                                    takes to complete */
} CodecCapabilities;

typedef CodecCapabilities *CodecCapabilitiesPtr;
flags
Contains flags that contain control information that is used by both the Image Compression Manager and the compressor component. The defined bit positions for this field are discussed later in this section.
wantedPixelSize
Indicates the pixel depth the component can use with the specified image. The component determines the pixel depth of the image for the operation by examining the appropriate pixel map.
extendWidth
Specifies the number of pixels the image must be extended in width. If the component cannot accommodate the image at its given width, the component may request that the Image Compression Manager extend the width of the image by adding pixels to the right edge of the image. This is sometimes necessary to accommodate the component's block size.
extendHeight
Specifies the number of pixels the image must be extended in height. If the component cannot accommodate the image at its given height the component may request that the Image Compression Manager extend the height of the image by adding pixels to the bottom of the image. This is sometimes necessary to accommodate the component's block size.
bandMin
Contains the minimum image band height supported by the component. Components that can tolerate small values operate under a wider set of memory conditions.
bandInc
Specifies a common factor of supported image band heights. A component may support only image bands that are an even multiple of some number of pixels high. These components report this common factor in the bandInc field. Set this field to 1 if your component supports bands of any size.
pad
Reserved for use by Apple.
time
Indicates the number of milliseconds the operation will take to complete. If the compressor cannot determine this value, it sets this field to 0.

The flags field of the compressor capability structure contains flags that exchange control information between the Image Compression Manager and the compressor component. Components use flags in the low-order 16 bits to indicate their capabilities to the manager. The Image Compression Manager may use flags in the high-order 16 bits to pass control information to the component.

The following flags are defined:

#define codecCanScale                       (1L<<0)     /* decompressor scales
                                                            information */
#define codecCanMask                        (1L<<1)     /* decompressor applies mask to
                                                            image */
#define codecCanMatte                       (1L<<2)     /* decompressor blends image using
                                                            matte */
#define codecCanTransform                   (1L<<3)     /* decompressor works with complex
                                                            placement matrices */
#define codecCanTransferMode                (1L<<4)     /* decompressor accepts transfer
                                                            mode */
#define codecCanCopyPrev                    (1L<<5)     /* compressor updates previous
                                                            image buffer */
#define codecCanSpool                       (1L<<6)     /* component can use functions to
                                                            spool data */
#define codecCanClipVertical                (1L<<7)     /* decompressor clips image
                                                            vertically */
#define codecCanClipRectangular             (1L<<8)     /* decompressor clips image
                                                            vertically & horizontally */
#define codecCanRemapColor                  (1L<<9)     /* compressor remaps color */
#define codecCanFastDither                  (1L<<10)    /* compressor supports fast
                                                            dithering */
#define codecCanSrcExtract                  (1L<<11)    /* compressor extracts portion
                                                            of source image */
#define codecCanCopyPrevComp                (1L<<12)    /* compressor updates previous
                                                            image buffer */
#define codecCanAsync                       (1L<<13)    /* component can work
                                                            asynchronously */
#definecodecCanMakeMask                     (1L<<14)    /* decompressor makes
                                                            modification masks */
#define codecCanShift                       (1L<<15)    /* component works with pixels
                                                            that are not byte-aligned */

The following flags are currently unused by the Image Compression Manager: codecCanClipVertical , codecCanClipRectangular , and codecCanFastDither .

Flag descriptions

codecCanScale
Indicates whether the decompressor can scale the image during decompression. The decompressor sets this flag to 1 to indicate that it can scale the image during decompression. The decompressor sets this flag to 0 if it cannot scale the decompressed image.
codecCanMask
Indicates whether the decompressor can apply a mask to the decompressed image. The decompressor sets this flag to 1 to indicate that it can use a mask to control the image that results from a decompression operation. The decompressor sets this flag to 0 if it cannot work with masks.
codecCanMatte
Indicates whether the decompressor can blend the decompressed image using a matte. The decompressor sets this flag to 1 to indicate that it can use a blend matte during decompression. The decompressor sets this flag to 0 if it cannot use a blend matte.
codecCanTransform
Indicates whether the decompressor can work with complex placement matrixes. The decompressor sets this flag to 1 to indicate that it can work with transformation matrixes during decompression. The decompressor sets this flag to 0 if it cannot work with matrixes.
codecCanTransferMode
Indicates whether the decompressor can accept a transfer mode other than source copy or dither copy when displaying a decompressed image. The decompressor sets this flag to 1 to indicate that it can accept transfer modes; otherwise, the decompressor sets this flag to 0.
codecCanCopyPrev
Indicates whether the compressor can update the previous image buffer during sequence compression. The compressor sets this flag to 1 to indicate that it can update the previous image buffer. The compressor sets this flag to 0 if it cannot update the buffer.
codecCanSpool
Indicates whether the component can use data-loading and data-unloading functions to spool data during decompression and compression operations, respectively. Applications may define data-loading and data-unloading functions to handle images that cannot fit into memory (see the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information on data-loading and data-unloading functions). The component sets this flag to 1 to indicate that it can use these functions. The component sets this flag to 0 to indicate that it cannot use these functions.
codecCanClipVertical
Indicates whether the decompressor can clip an image vertically during decompression. The decompressor sets this flag to 1 to indicate that it can clip an image vertically. The decompressor sets this flag to 0 to indicate that it cannot clip an image vertically.
codecCanClipRectangular
Indicates whether the decompressor can clip both vertically and horizontally during decompression. The decompressor sets this flag to 1 to indicate that it can clip along both axes. The decompressor sets this flag to 0 to indicate that it cannot clip an image both vertically and horizontally.
codecCanRemapColor
Indicates whether the compressor can remap the colors for an image using color tables. The compressor sets this flag to 1 if it can remap colors. The compressor sets this flag to 0 if it cannot remap colors.
codecCanFastDither
Indicates whether the compressor supports fast dithering. The compressor sets this flag to 1 if it supports fast dithering. The compressor sets this flag to 0 if it does not support fast dithering. See the chapter "Image Compression Manager" in Inside Macintosh: QuickTime for more information about fast dithering.
codecCanSrcExtract
Indicates whether the compressor can extract a portion of the source image. The compressor sets this flag to 1 if it can extract a portion of the source image. The compressor sets the flag to 0 if it cannot.
codecCanCopyPrevComp
Indicates whether the compressor can update the previous image buffer during sequence compression using compressed data. The compressor sets this flag to 1 to indicate that it can update the previous image buffer. The compressor sets this flag to 0 if it cannot update the buffer.
codecCanAsync
Indicates whether the component can work asynchronously. The compressor sets this flag to 1 if it can compress and decompress asynchronously; otherwise, it sets this flag to 0.
codecCanMakeMask
Indicates whether the decompressor creates modification masks during decompression. These masks indicate which pixels in the decompressed image differ from the previous image and must therefore be displayed. Such masks are useful only when processing sequences. The decompressor sets this flag to 1 to indicate that it creates modification masks. The decompressor sets this flag to 0 if it does not create such masks.
codecCanShift
Indicates whether the component can work with pixels that are not byte-aligned. This flag is valid only when the source or destination uses fewer than 8 bits per pixel. Components set this flag to 1 if they can read or write pixels that are not byte-aligned. Components set this flag to 0 if pixels must be byte-aligned.
© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next